/*
 $Id$

 Copyright (C) 2006-2007 by David Cotton

 This program is free software; you can redistribute it and/or modify it under
 the terms of the GNU General Public License as published by the Free Software
 Foundation; either version 2 of the License, or (at your option) any later
 version.

 This program is distributed in the hope that it will be useful, but WITHOUT
 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

 You should have received a copy of the GNU General Public License along with
 this program; if not, write to the Free Software Foundation, Inc., 51 Franklin
 Street, Fifth Floor, Boston, MA 02110-1301, USA.
 */
package fr.free.jchecs.ai;

import java.util.Comparator;

import fr.free.jchecs.core.move.Move;
import fr.free.jchecs.core.move.MoveGenerator;

/**
 * Interface presents the AI engine for playing chess.
 * 
 * @author David Cotton
 */
public interface Engine {
	/**
	 * Returns the total time spent in treatment by the engine.
	 * 
	 * @return Total processing time by the engine (in ms).
	 */
	long getElapsedTime();

	/**
	 * Returns the total number of half-moves to be evaluated by the engine.
	 * 
	 * @return Total half-moves evaluated by the engine.
	 */
	int getHalfmoveCount();

	/**
	 * Reference the evaluation function used by the engine.
	 * 
	 * @return Evaluation function used.
	 */
	Heuristic getHeuristic();

	/**
	 * Reference upper limit of the depth of research supported by the engine.
	 * 
	 * @return Maximum depth research (>= getMinimalSearchDepth()).
	 */
	int getMaximalSearchDepth();

	/**
	 * Reference lower limit of the depth of research supported by the engine.
	 * 
	 * @return Limite basse de la profondeur de recherche (>= 1).
	 */
	int getMinimalSearchDepth();

	/**
	 * Research a movement responding to a state of the exchequer.
	 * 
	 * @param pEtat
	 *            State of the chessboard.
	 * @return Movement found.
	 */
	Move getMoveFor(final MoveGenerator pEtat);

	/**
	 * Reference the sorting function of the movements.
	 * 
	 * @return Sorting function of the movements.
	 */
	Comparator<Move> getMoveSorter();

	/**
	 * Returns the score calculated by the last movement.
	 * 
	 * @return Score of the last movement.
	 */
	int getScore();

	/**
	 * Indicates whether to use the opening book is selected.
	 * 
	 * @return Limit the search depth ([getMinimalSearchDepth(),
	 *         getMaximalSearchDepth()]).
	 */
	int getSearchDepthLimit();

	/**
	 * Indicates whether to use the opening book is selected.
	 * 
	 * @return "true" if the openings are used, false otherwise.
	 */
	boolean isOpeningsEnabled();

	/**
	 * Modifies the evaluation function used by the engine.
	 * 
	 * @param pHeuristique
	 *            New evaluation function to use.
	 */
	void setHeuristic(final Heuristic pHeuristique);

	/**
	 * Alters the function of totally ordered movements.
	 * 
	 * @param pComparateur
	 *            New function sort of movement.
	 */
	void setMoveSorter(final Comparator<Move> pComparateur);

	/**
	 * Enables / disables the use of the library opening.
	 * 
	 * @param pActif
	 *            A "true " to enable the use of openings, "false" otherwise.
	 */
	void setOpeningsEnabled(final boolean pActif);

	/**
	 * Food value of the limit of search depth (in half moves).
	 * 
	 * @param pLimite
	 *            Limit the search depth ([getMinimalSearchDepth(),
	 *            getMaximalSearchDepth()]).
	 */
	void setSearchDepthLimit(final int pLimite);
}
